id: task-100.7 title: Bundle web assets into executable status: Done assignee: [] created_date: '2025-06-22' updated_date: '2025-07-06' labels: [] dependencies:

• task-100.1
• task-100.2
• task-100.6 parent_task_id: task-100

Description

Configure build process to embed React app in CLI executable. This is crucial for distributing Backlog as a single binary that contains both the CLI and web UI.

Build Process Overview

Build Process Requirements

Two-Stage Build:

1. Build React app to optimized static files
2. Embed static files into CLI executable using Bun's native directory embedding

Asset Embedding Strategy (Bun v1.2.17+):

• Use shell glob patterns with bun build --compile to embed directories
• Leverage Bun's native Bun.embeddedFiles API for accessing embedded assets
• Eliminate need for custom build scripts and manual asset generation

Native Directory Embedding:

• Use bun build --compile ./src/cli.ts ./src/web/dist/**/*.* --outfile=backlog
• Access embedded files via Bun.embeddedFiles array of Blob objects
• Automatically handles asset discovery and embedding

Vite Configuration Requirements:

• Configure production build optimization
• Set up code splitting for vendor libraries
• Enable proper asset hashing for cache busting
• Optimize bundle size with tree shaking and minification

Static Asset Serving:

• Access embedded files using Bun.embeddedFiles API
• Map file paths to embedded Blob objects
• Handle proper MIME types for different file extensions
• Implement appropriate caching headers
• Support SPA routing (fallback to index.html)

Package Scripts Integration:

• Simplify build process using native embedding
• Build script: bun build --compile ./src/cli.ts ./src/web/dist/**/*.* --outfile=backlog
• Eliminate need for separate asset embedding step
• Support both development and production builds

Embedded File Access:

• Use Bun.embeddedFiles to get array of all embedded files
• Each file is a Blob object with metadata
• Map original file paths to embedded file references
• Handle file serving directly from embedded Blobs

Reference Documentation

Essential Reading for Implementation:

• Bun Single-file Executables - Official documentation on bun build --compile
• Bun v1.2.17 Blog Post - Release notes covering directory embedding improvements
• Bun.embeddedFiles API - How to access embedded files at runtime

Key Implementation Patterns:

• Use shell glob patterns to embed directories: ./src/web/dist/**/*.*
• Access embedded files via Bun.embeddedFiles array
• Serve files directly from Blob objects without conversion

Optimization Techniques

• Code Splitting: Separate vendor chunks for better caching
• Tree Shaking: Remove unused code
• Minification: Terser for JS, cssnano for CSS
• Compression: Brotli compression for text assets
• Asset Hashing: For cache busting
• Lazy Loading: Dynamic imports for route-based splitting

Acceptance Criteria

• [x] Vite builds React app to optimized dist/ directory
• [x] Shell glob pattern embeds entire dist/ directory using bun build --compile
• [x] Embedded assets accessible via Bun.embeddedFiles API
• [x] Server can serve embedded files directly from Blob objects
• [x] Build process simplified without custom embedding scripts
• [x] Production build is optimized with proper asset hashing
• [x] SPA routing works correctly with embedded index.html fallback
• [x] All file types (HTML, CSS, JS, images) served with correct MIME types